home *** CD-ROM | disk | FTP | other *** search
/ Aminet 1 (Walnut Creek) / Aminet - June 1993 [Walnut Creek].iso / aminet / text / misc / makeguide1_49.lha / readme.amiga < prev    next >
Text File  |  1992-10-28  |  10KB  |  218 lines
  1.  
  2.  
  3.  
  4.  
  5.                                makeinfo 1.49
  6.  
  7.  
  8.       A modified GNU makeinfo by Reinhard Spisser and Sebastiano Vigna
  9.  
  10.  
  11.                                 October 1992
  12.  
  13.  
  14. This program is distributed under the GNU General Public License. Please
  15. refer to the COPYING file for details.
  16.  
  17. If you want to write your own Texinfo documentation (and not just converting
  18. pre-existing Texinfo docs), you will need the GNU Texinfo distribution,
  19. available on many ftp sites (e.g., prep.ai.mit.edu). This distribution
  20. archive contains also an executable version of texindex, so that you don't
  21. need any other file in order to fully exploit Texinfo. Should this
  22. distribution archive not contain the full sources of texindex and makeinfo,
  23. you can get them by sending a self-addressed, stamped envelope and a disk to
  24. either one of the authors, or by searching for the complete distribution on
  25. an ftp site.
  26.  
  27.  
  28. (Note that from this release makeinfo is a Release 2 only program, but you
  29. won't need the ixemul.library, because makeinfo has been compiled under the
  30. GNU 2.2 port by Davide Pasetto of Agemo; for the same reason, you can stop
  31. at any time the program via CTRL-C, or suspend it in wait state via CTRL-D;
  32. in the latter case, you can resume via CTRL-E).
  33.  
  34.  
  35. This project started with the idea of bringing to the Amiga community a set
  36. of tools which would have greatly simplified the handling of on-line help as
  37. opposed to a printed manual. Currently, the Amiga programmer has to keep two
  38. separate files which have to be updated in parallel. If also some hypertext
  39. feature is desired, the document writer has to keep a third version of the
  40. file (since AmigaGuide® is still not enough spread that one can assume the
  41. user will have it somehow).
  42.  
  43. This is unbearable. And indeed, the GNU people have found a great way of
  44. working around this problem. It's called Texinfo.
  45.  
  46. A Texinfo document is written in a very simple dialect of TeX that is easy
  47. to learn and use, and it's specifically tailored for the creation of
  48. technical manuals. Texinfo focuses on logical aspects---so the @t{} command,
  49. which typeset in fixed width font whatever is in the braces, should be never
  50. used, and rather replaced with @code{}, @file{} or @key{}, depending on the
  51. semantics of the text involved. This also ensures that each user can
  52. customized its Texinfo macros in such a way to spot out specific parts of a
  53. Texinfo file, or to set a different page size, text formatting etc.
  54.  
  55. Of course, the format has to be rich enough to express all the needs of a
  56. technical manual, and small enough to allow a decent translation of all the
  57. available constructs to plain ASCII (for an hypotetical hypertext viewer).
  58. Also in this respect Texinfo is an excellent balance.
  59.  
  60. Full documentation is available on how to write a Texinfo document. It is
  61. written, of course, in Texinfo, and is very clear. You should be able to
  62. start authoring a Texinfo document in an hour or so. If you're used to TeX,
  63. ten minutes will suffice. This documentation can be found on most ftp sites
  64. which have GNU stuff. The latest version of Texinfo we know of is 2.16. It's
  65. a final, very stable version.
  66.  
  67. Once a Texinfo document is ready, it can be converted in one of the
  68. following ways:
  69.  
  70. 1) It can be passed through TeX using the set of macros texinfo.tex. You
  71. will get a beautiful printed manual.
  72.  
  73. 2) It can be passed through the standard makeinfo in its Info mode; it will
  74. generate an Info document (Info is the GNU hypertext reader). This is not
  75. much of interest for you.
  76.  
  77. 3) It can be passed through makeinfo with the --no-headers option; it will
  78. generate an almost plain ASCII text file (cross references and indices will
  79. still be in Info style).
  80.  
  81. But with our version of makeinfo,
  82.  
  83. 4) It can be passed through makeinfo with the new --amiga option; it will
  84. generate an AmigaGuide® document; cross references, menus and indices will
  85. become buttons.
  86.  
  87. 5) It can be passed through makeinfo with the --amiga --no-headers options;
  88. it will generate a plain ASCII text file.
  89.  
  90. Thus, you have to maintain just a document in order to produce a printed
  91. manual, on-line hypertext documentation and plain ASCII documentation.
  92. Texinfo of course relies on a series of information you specify, like menus,
  93. cross references, etc., but the amount of work you'll need to do this will
  94. be very small. It also makes a great job in converting to ASCII---for
  95. instance, @emph{} text, which comes out slanted in the manual, is shown with
  96. two asterisk around. We would like to urge all of the Amiga community
  97. programmers, in particular the people distributing documentation as a file,
  98. to start using Texinfo. It will be an enormous quantum leap.
  99.  
  100. While we were working on the project, it became clear that much more was
  101. possible with this new tool. For instance, all of the GNU software comes
  102. with Texinfo documentation. It was a matter of a couple of minutes to make
  103. the Texinfo manual (500K!) into an AmigaGuide® file that we could browse at
  104. will, in full AmigaGuide® hypertext.
  105.  
  106.  
  107. Every port of this kind has of course some kind of tradeoff. Info and
  108. AmigaGuide® have a rather vaste intersection of features, but both have
  109. specific features that can't be mimicked on the other side.
  110.  
  111. The main design choice at the specification level was that *every* Texinfo
  112. should have been convertible to an AmigaGuide® file. And that *every*
  113. Texinfo file prepared for AmigaGuide® should have been convertible to Info
  114. format (this is essential, e.g., for people doing cross-development).
  115.  
  116. Fortunately, we were enough lucky: all Info features are translatable in
  117. AmigaGuide® features, excepted for file splitting; but AmigaGuide® doesn't
  118. load a file entirely---just loads a part of it. So even a 1 megabyte
  119. document is not a problem for it. Info instead relies on a splitting
  120. mechanism which is in makeinfo: this mechanism is disabled by the option
  121. --amiga.
  122.  
  123. There are also a couple of problem with the representation of buttons; Info
  124. does not have "real" buttons---it just put in the text something of the form
  125. "*Note Nodename::". Thus, the aspect of a line in Info or AmigaGuide® is
  126. very different. We chose to put in the button name only the "real title" of
  127. the button, i.e., the destination node name if nothing else is specified, or
  128. the second argument of a @ref, @xref or @pxref command if available.
  129. Moreover, we noted that the absence of "*Note"'s had made the text a bit
  130. unpleasant to read; so we inserted "see" and "See" whenever Texinfo would
  131. have done it in the printed text.
  132.  
  133. For menus, Texinfo relies on the visualisation of *both* the button name
  134. *and* the destination node name when building indices. Cutting away the
  135. destination node name would have resulted in a horribly looking index. So we
  136. decided to preserve the visualization of the destination node name after a
  137. menu button when building an index. A normal menu will instead show just a
  138. button.
  139.  
  140. Also, we slightly improved an aspect of @pxref. Since no ending point was
  141. needed before the closing parenthesis, we stripped it off.
  142.  
  143. All the features of Info which maps to AmigaGuide® have been implemented.
  144. Thus, the Top node of a Texinfo document will become the Main node of the
  145. AmigaGuide® file, the @master command will be set to the name of the Texinfo
  146. file, and the @width command will be set to the value makeinfo is using for
  147. formatting text.
  148.  
  149. The --no-headers option has now a better behaviour when also --amiga is
  150. selected. "*Note"'s are replaced by "see", etc.. The result is a completely
  151. human readable ASCII file.
  152.  
  153. It should also be noted that unfortunately Texinfo doesn't have any way of
  154. specifying a *line* in a node. So this feature of AmigaGuide® is not
  155. representable in a Texinfo file. This is indeed the biggest drawback of
  156. using Texinfo for writing AmigaGuide® documents. But we feel that the
  157. advantages are definitely overwhelming.
  158.  
  159. Due to the fact that AmigaGuide® is rather picky about the characters it
  160. allows in a button name or in a node name, at least for the time being
  161. makeinfo has to replace in a node name every slash or backslash with a dash
  162. and every quotes with a single open quote. Still, names with curly braces in
  163. them will behave incorrectly. But this is an AmigaGuide® problem.
  164.  
  165. Note that Texinfo doesn't support officially extended or accented
  166. characters. The workaround, for the time being, is to use ASCII extended
  167. characters like à, etc. in the text (in place of the various \`, etc.
  168. commands). Makeinfo will process the document flawlessly, and by including
  169. the amiga.tex file supplied in this distribution archive *before*
  170. texinfo.tex into your document, Texinfo will typeset correctly the accented
  171. characters (this should work on any TeX system which supports TeX 3.0; we
  172. tried successfully AmigaTeX and PasTeX). We would like to thank Tom Rokicki
  173. for allowing us to distribute the amiga.tex file, which is supplied in the
  174. distribution of Radical Eye's AmigaTeX.
  175.  
  176. Finally, we want to describe some bugs we found both in Texinfo and
  177. AmigaGuide®, whose knowledge can be helpful.
  178.  
  179. AmigaGuide® 33.1369 doesn't work properly if the name of a button contains
  180. an apostrophe ("'"). So you shouldn't use button names containing @code{},
  181. @samp{}, etc. (they are always forbidden in node names, but you can specify
  182. a button name different from the node name in an external reference
  183. command). The workaround is to not use apostrophes in button names
  184. (AmigaGuide® V34 and V39 doesn't suffer from this problem).
  185.  
  186. Texinfo 2.16 will insert an unnamed TOC entry for the Top node when the
  187. automatic pointer generation feature of makeinfo is used (that is, your Top
  188. node is defined via @node Top followed by @top). You should include the
  189. whole Top node in a @ifinfo/@end ifinfo pair for the time being.
  190.  
  191. Texinfo 2.16 will print an extra '*' while underlining chapters (when
  192. --no-headers is activated). In particular, a stand-alone asterisk will
  193. appear at the top of the document if you use the @top command.
  194.  
  195. (These bugs have been reported to GNU, of course).
  196.  
  197. Good Texinfoing! Please send any bug report or enhancement request to
  198.  
  199.  
  200.     Reinhard Spisser
  201.     Via Bonghi 15
  202.     I-20141 Milano MI
  203.  
  204.     BIX: reinhards
  205.     INTERNET: rein@bliss.st.dsi.unimi.it
  206.  
  207.  
  208.     Sebastiano Vigna
  209.     Via California 22
  210.     I-20144 Milano MI
  211.  
  212.     BIX: svigna
  213.     INTERNET: vigna@imiucca.csi.unimi.it
  214.               vigna@ghost.sm.dsi.unimi.it
  215.     UUCP:cbmehq!cbmita!sebamiga!seba@cbmvax.cbm.commodore.com
  216.          ...{uunet|pyramid|rutgers}!cbmvax!cbmehq!cbmita!sebamiga!seba
  217.     FIDO: 2:332/607.28
  218.